ctcert

ctcert is a certificate management utility for the ProtectToolkit-C environment, which provides basic support for the creation of X.509v3 certificates using ProtectToolkit-C. The tool's functions include:

• Generation of self-signed certificates and certificates signed with a specified CA key.

• Generation of PKCS#10 certificate requests.

• Listing certificates, certificate requests, and key objects that exist in a specified slot.

• Importing certificates (PEM format).

• Exporting certificates (PEM format).

• Marking certificates as trusted

The sections below list and describe the syntax, commands, and options of ctcert.

Syntax

The following ctcert syntax can can be used.

Commands

The following ctcert commands are available.

c

This command is used to generate X.509v3 certificates. A number of approaches are available using ctcert. These approaches and the minimum options required are listed below.

To generate new keys and self sign

ctcert c -k -l<label>[options ...]

To generate new keys and sign with a CA key

ctcert c -c<label> -k -l<label> [options...]

To use existing keys and self sign

ctcert c -l<label> [options...]

To use existing keys and sign with a CA key

ctcert c -c<label> -l<label> [options...]

One of the above combinations of options -c, -k, -l is mandatory. All other options allow finer control over the default actions of ctcert. A detailed description of each option is provided in Options.

If -l<label> is used without -k (generate new key pair), <label> is the label for an existing PKCS#10 certificate request or an existing public key. ctcert first searches for a certificate request with a matching label and uses it to generate the certificate. If a certificate request does not exist, ctcert searches for a public key with a matching label and uses it to generate a certificate. Otherwise, ctcert reports an error.

i

This command is used to import a new certificate or certificate request object onto the HSM. The object to be imported is PEM-encoded and contained in a text file. To verify the object is PEM-encoded, the first line in the text file should contain one of the following strings.

“----BEGIN CERTIFICATE----“
“----BEGIN CERTIFICATE REQUEST----“

The -l<label> option specifies the label for the newly-imported certificate or certificate request object.

l

This command will list the existing certificates, certificate requests and keys on the specified token.

r

This command generates a certificate request from an existing or newly-generated key pair. For an existing key pair, the -l<label> option specifies the label of the public key. The private key is identified by CKA_ID attribute, which should be the same for key pairs. This is the default behavior for keys generated by ProtectToolkit-C. If the public key contains a value for the CKA_SUBJECT attribute, then it will be used for the certificate request object’s subject-distinguished name. If this attribute does not exist, ctcert will prompt the user for this information.

If a new key pair is being generated, the -l<label> option specifies the label for the new key pair and ctcert will prompt for the certificate request object's subject-distinguished name. The new certificate request object's label will also be set to <label>.

t

This command will set the CKA_TRUSTED attribute on the specified certificate on the token. The SO is the only user who can set this attribute and the user will be prompted for the token SO PIN.

x

This command exports a certificate or certificate request object in a PEM-encoded format. The PEM encoding is written to standard output, or the file specified with the -f<file> option.

The -l<label> option specifies the object to export. If a certificate object with a matching label exists, it will be exported. Otherwise, ctcert will search for a certificate request with a matching label.

Options

The following ctcert options can be used with various commands, as shown in Syntax.

-b<YYYYMMDDhhmmss[Z]>, --cert-begin=<YYYYMMDDhhmmss[Z]>

Specifies the begin time (notBefore) for a Certificate. Including the Z sets the time as GMT. Otherwise, local time is assumed and is converted to GMT.

Note

This option is only valid for the Generate Certificate command (c), and must be used with either the -b<YYYYMMDDhhmmss[Z]> or -d<integer[h|d|m|y]> option.

-c<label>, --ca-label=<label>

Specifies a label identifying a CA (private) key used to sign a newly-generated certificate. The <label> can be a label for a certificate associated with the CA key, or the label of the private key itself.

Note

This option is only valid for the Generate Certificate command (c).

-C<curve_name>, --curve-name=<label>

Specifies which curve to use. Valid values:

• brainpoolP160r1

• brainpoolP160t1

• brainpoolP192r1

• brainpoolP192t1

• brainpoolP224r1

• brainpoolP224t1

• brainpoolP256r1

• brainpoolP256t1

• brainpoolP320r1

• brainpoolP320t1

• brainpoolP384r1

• brainpoolP384t1

• brainpoolP512r1

• brainpoolP512t1

• c2tnb191v1

• c2tnb191v1e

• curve25519

• ed25519

• P-192 (also known as prime192v1 and secp192r1)

• P-224 (also known as secp224r1)

• P-224K1 (also known as secp224k1)

• P-256 (also known as prime256v1 and secp256r1)

• P-384 (also known as secp384r1)

• P-521 (also known as secp521r1)

• secp256k1

• or any valid ECC Domain Parameter object label

Note

If -tec is specified, the -C parameter must be included in the command, or ctcert will exit with an error message.

All hashing mechanisms are supported.

-d<integer[h|d|m|y]>, --cert-duration=<integer[h|d|m|y]>

Specifies the duration of a Certificate. Must specify one of the following values:

h - hours

d - days

m - months

y - years

Note

This option is only valid for the Generate Certificate command (c).

Tip

can be used with the -b<YYYYMMDDhhmmss[Z]> option. If the -b option is not included, the duration will begin at the moment of creation.

-e<YYYYMMDDhhmmss[Z]>, --cert-end=<YYYYMMDDhhmmss[Z]>

Specifies the end time (notAfter) for a Certificate. Including the Z sets the time as GMT. Otherwise, local time is assumed and is converted to GMT.

Note

This option is only valid for the Generate Certificate command (c), and must be used with the -b<YYYYMMDDhhmmss[Z]> option.

-f<name>, --import-file=<name>

Specifies a text file containing a PEM encoding of a certificate or certificate request object.

Note

This option is only valid with the Import command (i) and Export command (x).

-h, -?, --help

Display usage information.

-i<slot>, --ca-slot=<slot>

Specifies the slot containing the CA signing key identified by the -c<label> option. If the -i<slot> option is not present, the CA key is assumed to be in the slot identified by the -s<slot> option. If -s is not present, then the CA key is assumed to exist in slot 0. If the CA signing key has the CKA_SIGN attribute set to FALSE and the CKA_SIGN_LOCAL_ATTRIBUTE set to TRUE, the CA signing key must reside in the same slot as the certificate it is signing.

Note

This option is only valid with the -c option.

-k, --key-gen

Specifies that a new key pair be generated. The l<label> option specifies the label for the new keys. A key pair with the same label must not already exist.

Note

-k is a mandatory parameter when generating a certificate with new keys.

-l<label>, --label=<label>

This option specifies a label for a new or existing certificate request or public key object. Refer to the description of each command for relevant details.

-P, --P

This option will sign the newly created certificate using an RSA-PSS mechanism. This option is only valid if the key used to sign the certificate is RSA.

--rsaPubLen<bits>

This option specifies the length (in bits) of a random RSA public exponent.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

--rsaPubVal<hex-string>

This option specifies the value of the RSA public exponent as a HEX string.

Note

This option is only available if you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer.

-s<slot>, --slot=<slot>

Specifies the slot:

• in which a new key pair and a certificate or certificate request will be generated.

• into which a certificate or certificate request will be imported.

• from which keys, certificates, and certificate requests will be listed.

• that contains the certificate or certificate request to be exported.

-S<mechanism>, --sig-hash-alg=<sign_alg>

Specifies the RSA or DSA hashing algorithm for certificate request or certificate generation.

Valid RSA/ECDSA mechanisms are:

• SHA1 (Default)

• SHA224

• SHA256

• SHA384

• SHA512

• SHA3-224

• SHA3-256

• SHA3-384

• SHA3-512

Valid DSA mechanisms are:

• SHA1 (Default)

• SHA224

• SHA256

• SHA384

• SHA512

Note

ECDSA is used for a certificate and EC is used for a key pair.

-t<type>, --type=<type>

Use with the -k option to specify the key type that should be generated. The valid key types are rsa (Default), rsax931, ec, and dsa.

Note

If -tec is specified, the -C parameter must be included in the command, or ctcert will exit with an error message. All hashing mechanisms are supported.

If -t is set to rsa or rsax931 and values are not specified for --rsaPubLen and --rsaPubVal, then the default is to use a random exponent of length 16 for rsa and length 17 for rsax931

-x<name>, --attribute-file=<name>

Specifies a text file containing certain certificate attributes and extensions. For details on supported attributes and extensions and the format of this file refer to Certificate Attribute File.

Note

This option is only valid with the Generate Certificate command (c).

-z<bits>, --size=<bits>

Use with the -k option to specify the new key size in bits. The default key size is 1024 bits.

Certificate attribute file

The certificate attribute file allows the user to specify certain certificate attributes, including extensions, that should be used when generating a new certificate. The supported attributes and extensions are:

• Certificate label

• Certificate serial number

• Certificate issuer-distinguished name

• Certificate subject-distinguished name

• Certificate policies extension with support for a certification practice statement (CPS) or user notice

• Certificate key usage extension

• Certificate subject alternative name (SAN) extension

Format

The format for specifying an attribute or extension is:

<tag> { <value> , <value> , ... }

White space is ignored throughout the file, except where it occurs within a <value> string.

Valid tags

The valid <tags> are:

• label

• serialnumber

• issuer

• subject

• certificatepolicies

• keyusage

• subjectaltname

See the sections below for the allowed values for each of these tags.

label

This tag defines the certificate’s label and is different from the label specified by the l<label> option. This latter label refers to the key pair for which the certificate is being generated. If this tag is missing in the certificate attribute file, then the certificate label will default to the one specified with the -l<label> option.

The label can be any string of ASCII characters. If the label contains multiple words, white space between the words is maintained. If a new line is encountered between words it is replaced by a space.

Example label tag usage

label { Test Certificate }

serialnumber

This tag defines the certificate’s serial number. To ensure uniqueness, it is only used if the signing key does not have the usage count attribute defined. If this attribute is defined, the current value of the usage count is used as the certificate’s serial number. If the usage count attribute is not defined and the serial number is not defined in the certificate attribute file, then ctcert will prompt the user for this information.

The maximum value of a certificate serial number is 99999999.

Example serialnumber tag usage

serialnumber { 999999 }

issuer | subject

These tags define the issuer and subject distinguished names and are defined by a set of name/value pairs. The format for an issuer or subject distinguished name is:

issuer | subject {

CN=<string> ,

OU=<string> ,

O=<string> ,

C= <string>

}

The meaning of each name component in each name/value pair is as follows:

CN - Common Name

OU - Organizational Unit Name

O - Organization Name

C - Country Name

Example issuer tag usage

issuer
 { CN=any string ,
  OU=Testing ,
  O=SafeNet , 
 C=CA 
 }

Note

White space is ignored except when it appears between multiple words that constitute the value component of a name/value pair. In the above example, the space between any string in the common name component is preserved.

For the subject-distinguished name tag, two special strings can be assigned to the CN (Common Name) component. These special strings are serialno and unique.

When the serialno string is used, ctcert will replace the serialno string with the HSM's serial number. This can be used to distinguish certificates that belong to specific HSMs.

When the unique string is used, ctcert appends the current value of the signing key’s usage count to the HSM serial number and replaces the unique string with this value. Thus the unique string will be replaced with a string of the form nnnn-xx, where nnnn is the HSM serial number and xx is the signing key’s usage count.

certificatepolicies

This tag identifies a certificate policies extension that defines the policy under which this certificate was issued. The format of a certificate policy extension entry is:

**certificatepolicies { **

oid=oid_string ,

[critical | noncritical , ]

[unotice=<string> , ]

[cps=<string> ]

}

The certificate policy is identified by an object identifier (OID) and may contain one of the policy qualifiers cps or unotice. The cps qualifier string is the URI of the Certification Practice Statement that relates to this policy, and the unotice qualifier is a string that is included in the certificate as a user notice that relates to the certificate policy. Both the cps and unotice strings are composed of printable ASCII characters. An object identifier (OID) is defined by a series of numerical labels separated by periods. For example, the OID that identifies a key usage extension within an X.509v3 certificate is written as:

id-ce-keyusage OBJECT IDENTIFIER ::= { 2.5.29.15 }

The critical/noncritical keywords indicate whether this certificate policy extension is critical or not. By default, the certificate policy extension is marked noncritical. Multiple certificate policy extensions can be defined in the certificate attribute/extension file.

Example certificatepolicies tag usage

certificatepolicies
{
    oid=1.2.3.45.6.8 ,
unotice=Test string,
critical
}</pre>

keyusage

This extension restricts the usage of the public key in the certificate. The format of the keyusage entry is:

keyusage{

<key usage string> ,

[ <key usage string> , ]

[ critical | noncritical , ]

}

The <key usage strings> conform to those defined in RFC2459 and acceptable values are:

- **digitalSignature**

- **nonRepudiation**

- **keyEncipherment**

- **dataEncipherment**

- **keyAgreement**

- **keyCertSign**

- **cRLSign**

- **encipherOnly**

- **decipherOnly**

The critical/noncritical keywords indicate whether this key usage extension is critical or not. By default the key usage extension is marked critical.

Example keyusage tag usage

keyusage{digitalSignature ,keyCertSign}

subjectaltname

This tag identifies a certificate SAN extension that defines all domain names that are secured by the certificate. The format of the SAN entry is:

subjectaltname {

dnsname=<string> ,

[ critical | noncritical ]

}

The certificate SAN only supports a GeneralName specified in [2] IA5String (dNSName) format via the dnsname keyword. The dnsname string is composed of printable ASCII characters. Multiple domain names can be defined in the dnsname string separated by semicolons.

The critical/noncritical keywords indicate whether this certificate SAN extension is critical or not. By default, the certificate SAN extension is marked noncritical.

Example subjectaltname tag usage

subjectaltname
{
dnsname=www.thalesdocs.com; thalesdocs.com,
critical
}

ctcert c  -k  -lTest  -tdsa

ctcert c  -c”CA Key”  -k  -lTest -z512

ctcert c  -tec -CP-192 -lecdsaCert1 -k

ctcert c  -lTest  -x certificate_file.txt

ctcert c  -c”CA Key”  -lTest

ctcert c  -c”CA Key”  -l”Test Cert”

ctcert r  -k  -lUser

ctcert x  -lUser -fmycert.txt

ctcert c -k -s0 -ltest1234 -t rsa -z2048 -P -S sha512